<html>
<head><meta charset="utf-8"><title>documenting stabilized features · t-lang/doc · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/index.html">t-lang/doc</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html">documenting stabilized features</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="239381332"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239381332" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239381332">(May 19 2021 at 07:53)</a>:</h4>
<p>I think I would like to make it a requirement of stabiliztion that we document the features in the reference. There was an RFC to this effect as I require, and sometimes we do, but I don't feel like we've made it as complete a part of our procedure as we could (am I wrong?). To start, I created a column of things that need documenting in our project board, but I wanted to open up the topic for the best way to go about working towards completeness of the reference</p>



<a name="239414297"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239414297" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239414297">(May 19 2021 at 12:30)</a>:</h4>
<p>The only way to require docs is to have reviewers require the docs to be written.  The process is written down, it's no secret, but some people don't want to do it.  Maybe better understanding of why that is could help.</p>



<a name="239422428"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422428" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422428">(May 19 2021 at 13:20)</a>:</h4>
<p>I have two thoughts</p>



<a name="239422454"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422454" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422454">(May 19 2021 at 13:21)</a>:</h4>
<ul>
<li>I am not convinced that reference material should block stabilization, but maybe it should</li>
</ul>



<a name="239422499"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422499" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422499">(May 19 2021 at 13:21)</a>:</h4>
<p>I like the way that Ember phrasing things:</p>



<a name="239422526"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422526" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422526">(May 19 2021 at 13:21)</a>:</h4>
<p>there is a phase where things are <em>stable</em> and a distinct phase where they are <em>recommended for use</em></p>



<a name="239422533"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422533" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422533">(May 19 2021 at 13:21)</a>:</h4>
<p>however</p>



<a name="239422548"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422548" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422548">(May 19 2021 at 13:21)</a>:</h4>
<p>it is quite likely that this should be the exception, not the norm</p>



<a name="239422583"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422583" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422583">(May 19 2021 at 13:21)</a>:</h4>
<p>I think then the other problem is</p>



<a name="239422634"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422634" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422634">(May 19 2021 at 13:22)</a>:</h4>
<ul>
<li>we have no template or checklist for stabilization reports</li>
</ul>



<a name="239422648"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422648" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422648">(May 19 2021 at 13:22)</a>:</h4>
<p>this we can fix relatively easily!</p>



<a name="239422682"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239422682" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239422682">(May 19 2021 at 13:22)</a>:</h4>
<p><span class="user-mention silent" data-user-id="120518">Eric Huss</span> <a href="#narrow/stream/237824-t-lang.2Fdoc/topic/documenting.20stabilized.20features/near/239414297">said</a>:</p>
<blockquote>
<p>The process is written down, it's no secret</p>
</blockquote>
<p>in other words, I don't really agree with this =)</p>



<a name="239423162"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239423162" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239423162">(May 19 2021 at 13:25)</a>:</h4>
<p>I think there is at least a checklist written here: <a href="https://rustc-dev-guide.rust-lang.org/stabilization_guide.html">https://rustc-dev-guide.rust-lang.org/stabilization_guide.html</a>, along with some (semi-broken) links to example reports.  The first section there spells out what needs to be done documentation-wise.</p>



<a name="239423509"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239423509" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239423509">(May 19 2021 at 13:27)</a>:</h4>
<p>I also find that the documentation phase is a good process for ensuring that you are stabilizing what you think you are stabilizing.</p>



<a name="239423831"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239423831" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Eric Huss <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239423831">(May 19 2021 at 13:29)</a>:</h4>
<p>I think it's fine if someone doesn't want to write the documentation for whatever reason, but I think it would be good to somehow make it part of the process. Either enlisting someone to help, or at least writing a good stabilization report that outlines what the thing does.</p>



<a name="239426312"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239426312" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239426312">(May 19 2021 at 13:44)</a>:</h4>
<p><span class="user-mention silent" data-user-id="120518">Eric Huss</span> <a href="#narrow/stream/237824-t-lang.2Fdoc/topic/documenting.20stabilized.20features/near/239423509">said</a>:</p>
<blockquote>
<p>I also find that the documentation phase is a good process for ensuring that you are stabilizing what you think you are stabilizing.</p>
</blockquote>
<p>yes</p>



<a name="239426332"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239426332" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239426332">(May 19 2021 at 13:44)</a>:</h4>
<p><span class="user-mention silent" data-user-id="120518">Eric Huss</span> <a href="#narrow/stream/237824-t-lang.2Fdoc/topic/documenting.20stabilized.20features/near/239423831">said</a>:</p>
<blockquote>
<p>I think it's fine if someone doesn't want to write the documentation for whatever reason, but I think it would be good to somehow make it part of the process. Either enlisting someone to help, or at least writing a good stabilization report that outlines what the thing does.</p>
</blockquote>
<p>I agree</p>



<a name="239426365"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/237824-t-lang/doc/topic/documenting%20stabilized%20features/near/239426365" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/237824-t-lang/doc/topic/documenting.20stabilized.20features.html#239426365">(May 19 2021 at 13:44)</a>:</h4>
<p><span class="user-mention silent" data-user-id="120518">Eric Huss</span> <a href="#narrow/stream/237824-t-lang.2Fdoc/topic/documenting.20stabilized.20features/near/239423162">said</a>:</p>
<blockquote>
<p>I think there is at least a checklist written here: <a href="https://rustc-dev-guide.rust-lang.org/stabilization_guide.html">https://rustc-dev-guide.rust-lang.org/stabilization_guide.html</a>, along with some (semi-broken) links to example reports.  The first section there spells out what needs to be done documentation-wise.</p>
</blockquote>
<p>yeah, there's some docs, I just think they could be improved</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>